Technotools/Technotools (Chestnut CD-ROM)(1993).ISO/lang_c/cug191/sound.doc

Text File | 1986-03-05 | 43KB | 1,118 lines

.op











                    S O U N D   E F F E C T S

                       C Function Library
                          Version 1.0b


               Copyright (C) 1986 by Paul Canniff
                      All Rights Reserved.




                          Paul Canniff
                          P.O. Box 1056
                        Marlton NJ 08053

                    CompuServe ID 73047,3715
























                                                Updated 05 Mar 86
.paè



                         C O N T E N T S

          Introduction  .......................  1
          Installation for Aztec C  ...........  2
          Installation for Ecosoft C  .........  3
          Installation for Lattice C  .........  4
          Installation for other compilers  ...  5
          Using The Library  ..................  6
          Making Music (using PLAY)  ..........  8
          Making Noise (using SOUND)  ......... 10
          Function Summary List  .............. 11
          Individual Function Descriptions  ... 12
          Technical Information  .............. 18
          What To Do When It Doesn't Work  .... 23
          Change Log .......................... 24
.paè.pn 1

                          Introduction

Thi≤ librar∙ facilitate≤ thσ usσ oµ sounΣ anΣ musiπ oε thσ IBM-P├ ì
famil∙á anΣá compatibles«á  I⌠ ha≤ beeε testeΣ witΦá thσá Latticσ ì
compile≥á versioε 2.1╡ anΣ thσ Man° Azteπ compile≥ versioεá 3.20«  ì
Othe≥ compiler≤ (o≥ version≤ oµ thesσ compilers⌐ shoulΣ worδ jus⌠ ì
fine¼á provideΣá yo⌡ caε rewritσ o≥ modif∙ thσá assembly-languagσ ì
portions«á  ╔á wil∞ bσ glaΣ t∩ hel≡ ge⌠ thσ librar∙ workinτá witΦ ì
other compilers.

Thσá maiεá function≤ iε thσá librar∙á arσá play()¼á sound()¼á anΣ ì
sounds()«á  Play(⌐á accept≤á ß forφ oµá musica∞á notation¼á whilσ ì
sounds(⌐á anΣ sounds(⌐ accep⌠ specifiπ frequencie≤ anΣá duration≤ ì
fo≥á greate≥á flexibilit∙á (a⌠ thσ expensσ oµ morσ worδá fo≥á thσ ì
programmer)«  Thesσ function≤ arσ discusseΣ iε morσ detai∞ iε thσ ì
section≤ "Makinτ Musicó anΣ "Makinτ Noise"«  Call≤ t∩ sound(⌐ anΣ ì
play(⌐áá caεá bσá freel∙á intermixeΣá iεá eithe≥á foregrounΣáá o≥ ì
background¼á providinτá ßá flexiblσ high-leve∞ interfacσá t∩á thσ ì
speaker.

Al∞á oµá thesσá sound-makinτ routine≤ caε ruεá iεá foregrounΣá o≥ ì
background«  ForegrounΣ mean≤ tha⌠ thσ sounΣ i≤ generateΣ iε mucΦ ì
thσá samσá wa∙á tha⌠ mos⌠ othe≥á P├á outpu⌠á i≤á generated╗á  thσ ì
applicatioεá request≤ tha⌠ i⌠ bσ done¼á thσ drive≥ doe≤á it¼á anΣ ì
theε i⌠ return≤ t∩ thσ application«á  Thi≤ i≤ straightforwarΣ anΣ ì
clean.

BackgrounΣ i≤ thσ fanc∙ way«á  Thσ musiπ o≥ thσ sounΣ effect≤ arσ ì
requesteΣá b∙á thσ application¼á whicΦ caε theε continuσá t∩á ruε ì
whilσ thσ drive≥ control≤ thσ speaker«á  Thi≤ allow≤ yo⌡ t∩á pla∙ ì
somσá musiπá whilσ you≥ prograφ perform≤ somσá operations¼á whicΦ ì
might be better than just flashing WAIT at the user.

Iε addition¼á thσ librar∙ include≤ ß numbe≥ oµ low-leve∞ routine≤ ì
tha⌠ acces≤ thσ speake≥ directly«

.paè.he SounΣ Effect≤                                Genera∞ Installation

Thσá followinτá genera∞á installatioε procedurσá applie≤á t∩á al∞ ì
supporteΣ compilers«

(1)  First¼ se⌠ u≡ you≥ "worδ area"¼ whethe≥ i⌠ bσ ß subdirector∙ ì
áááááoεá ß harΣ disk¼á o≥ ß flopp∙ disk«á  Iµ yo⌡ havσ rooφ oεá ß ì
ááááácurren⌠ worδ disk¼á o≥ iε you≥ usua∞ ├ subdirectory¼ yo⌡ ma∙ ì
áááááwan⌠á t∩ usσ them«á  Whereve≥ yo⌡ decidσ upon¼á thi≤ disδ o≥ ì
ááááádiectory will be referred to as your "work area".

(2)á Cop∙ al∞ .├ anΣ .╚ file≤ froφ thσ distributioε disδ t∩á you≥ ì
áááááworδá area«á

(3)  Therσ arσ als∩ somσ assembly-langaugσ sourcσ file≤ whicΦ yo⌡ ì
áááááwil∞ need¼ calleΣ DELA┘ anΣ SOUNDINT«  Therσ arσ version≤ oµ ì
áááááthesσ file≤ oε thσ disδ fo≥ eacΦ supporteΣá compiler«á  Cop∙ ì
áááááthσá prope≥ file≤ t∩ you≥ worδ area¼á changinτ thσ extensioε ì
ááááát∩ .AS═ iε thσ process.

ááááá       AZTEC:    *.ASZ  ->  *.ASM
ááááá       LATTICE:  *.ASL  ->  *.ASM
ááááá       ECOSOFT:  *.ASE  ->  *.ASM

(*)  Kee≡á thσ origina∞ distributioε disδ iε ß safσá place╗á  al∞ ì
áááááfurthe≥ action≤ discusseΣ shoulΣ bσ donσ oε you≥ worδá area¼ ì
áááááno⌠ thσ distributioε disk.

(2)  Edi⌠á thσ filσ SOUND.╚ anΣ makσ surσ tha⌠ thσ onl∙á compile≥ ì
áááááflaτ se⌠ i≤ thσ onσ fo≥ you≥ compiler«á  Tha⌠ flaτ shoulΣ bσ ì
áááááset to 1, all others to 0.

(3)ááCompilσá thσ ├ files«á  The∙ includσ thσ followinτ ╚á files¼ ì
áááááwhich should be included with your compiler:

ááááá     Lattice, Ecosoft:     STDIO.H, DOS.H
ááááá     Aztec:                STDIO.H, MODEL.H

(4)  Assemblσá thσá .AS═ file≤ usinτ thσ assemble≥ provideΣá witΦ ì
áááááyou≥áá compiler¼áá thσá Miscrosof⌠áá Macr∩áá Assembler¼áá o≥ ì
áááááequivalent«á  Thσá followinτ "macroó header≤ arσ includeΣ b∙ ì
áááááthe assembly files:

ááááá     Lattice:       DOS.MAC
ááááá     (all others)   -none-

(5)ááThσá filσá SOUNDTS╘á i≤á no⌠ ß par⌠á oµá thσá SounΣá Effect≤ ì
ááááálibrary¼á bu⌠á i≤ furnisheΣ a≤ aε examplσ oµ aεá applicatioε ì
ááááácallinτá thσ sounΣ functions«á  T∩ tes⌠á thσá library¼á linδ ì
áááááSOUNDTS╘á t∩á al∞á thσ sounΣ functions¼á anΣá an∙á necessar∙ ì
ááááámodules.  The following modules are required:

ááááá     Lattice:       C.OBJ, LC.LIB
ááááá     Ecosoft:       ??
ááááá     Aztec:         C.LIB
.paè.he SounΣ Effect≤                         Installatioε - Man° » Aztec

             Manx Aztec C Version 3.20 Installation

Note:á Olde≥ Man° compiler≤ (sucΦ a≤ versioε 1.06⌐ shoulΣ requirσ ì
ááááááán∩ changσ t∩ thσ followinτ procedure.

Beforσá starting¼á se⌠á u≡á you≥ "worδ area"¼á whethe≥á i⌠á bσá ß ì
subdirectory on a hard disk, or a floppy disk.   Then ...

(1)á Cop∙á thσ .├ anΣ .╚ file≤ t∩ you≥ worδ diskettσ o≥ harΣ disδ ì
ááááásubdirectory«á  Cop∙á al∞ .AS╠ file≤ t∩ .AS═ file≤á oεá you≥ ì
áááááworδá area«á  Kee≡ thσ origina∞ distributioε disδ iε ßá safσ ì
áááááplace╗  al∞ furthe≥ action≤ discusseΣ shoulΣ bσ donσ oε you≥ ì
áááááworδ area¼ no⌠ thσ distributioε disk.

(2)  Edi⌠á thσ filσ SOUND.╚ anΣ makσ surσ tha⌠ thσ onl∙á compile≥ ì
áááááflag set to 1 is C_AZTEC.

(3)ááCompilσá thσ ├ files«á  The∙ includσ thσ followinτ ╚á files¼ ì
áááááwhich should be included with your compiler:

ááááá     STDIO.H     MODEL.H

(4)  Assemblσá thσá .AS═á file≤ usinτ thσ Man°á Azteπá Assembler¼ ì
áááááMiscrosof⌠ Macr∩ Assemble≥ o≥ equivalent.

(5)ááLinδá thσ filσ SOUNDTEST.OB╩ t∩ thσ res⌠ oµ .OBJ'≤á produceΣ ì
áááááb∙ thσ abovσ commands¼ anΣ t∩ thσ ├ librar∙ (C.LIB)«

(6)ááIµá yo⌡ hea≥ music¼á yo⌡ havσ correctl∙ installeΣ you≥ sounΣ ì
ááááároutines«á  Yo⌡á ma∙ usσ LI┬ o≥ PLIB8╢ t∩ forφ theφá int∩á ß ì
ááááálibrar∙ iµ yo⌡ want«á  Notσ tha⌠ yo⌡ wil∞ havσ t∩ repea⌠ thσ ì
áááááinstallatioε procedurσ fo≥ ever∙ memor∙ mode∞ yo⌡ use«á  Oh¼ ì
áááááyes¼á yo⌡á caε deletσ thσ SOUNDTS╘ file≤ wheε yo⌡ arσá done¼ ì
áááááthougΦ thσ sourcσ give≤ ß gooΣ examplσ oµ thσ correc⌠ wa∙ t∩ ì
áááááacces≤ thσ library.

                           Aztec Notes

(1)  Sound_done(⌐ mus⌠ als∩ bσ calleΣ beforσ exitinτ aεá overlay¼ ì
áááááiµ thσ overla∙ contain≤ thσ SounΣ Effect≤ codσ anΣ data«  Iµ ì
ááááábotΦá codσ anΣ datß oµ thσ SounΣ Effect≤ function≤ residσ iε ì
áááááthe root, this is not necessary.

.paè.he SounΣ Effect≤                              Installatioε - Ecosoft

               Ecosoft C Version 3.02 Installation

Beforσá starting¼á se⌠á u≡á you≥ "worδ area"¼á whethe≥á i⌠á bσá ß ì
subdirectory on a hard disk, or a floppy disk.   Then ...

(1)á Cop∙á thσ .├ anΣ .╚ file≤ t∩ you≥ worδ diskettσ o≥ harΣ disδ ì
ááááásubdirectory«á  Cop∙á al∞ .ASE file≤ t∩ .AS═ file≤á oεá you≥ ì
áááááworδá area«á  Kee≡ thσ origina∞ distributioε disδ iε ßá safσ ì
áááááplace╗  all furthe≥ action≤ discusseΣ shoulΣ bσ donσ oε you≥ ì
áááááworδ area¼ no⌠ thσ distributioε disk.

(2)  Edi⌠á thσ filσ SOUND.╚ anΣ makσ surσ tha⌠ thσ onl∙á compile≥ ì
áááááflag set to 1 is C_ECOSOFT.

(3)ááCompilσá thσ ├ files«á  The∙ includσ thσ followinτ ╚á files¼ ì
áááááwhich should be included with your Lattice Compiler:

ááááá     STDIO.H     DOS.H

(4)ááAssemblσá thσ .AS═ file≤ usinτ thσ Microsof⌠ Macr∩ Assemble≥ ì
áááááo≥ equivalent«á  Thσ filσ PRO.╚ mus⌠ bσ present«á  Thi≤ filσ ì
ááááái≤ includeΣ iε thσ Ecosoft ├ packagσ anΣ allow≤ thσ assembl∙ ì
ááááámodule≤ t∩ kno≈ thσ memor∙ mode∞ iε use.

(5)ááLinδá thσ filσ SOUNDTEST.OB╩ t∩ thσ res⌠ oµ .OBJ'≤á produceΣ ì
áááááb∙á thσá abovσá commands¼á anΣá t∩á thσá Ecosof⌠á ├á librar∙ ì
ááááá(ECOC.LIB)«

(6)ááIµá yo⌡ hea≥ music¼á yo⌡ havσ correctl∙ installeΣ you≥ sounΣ ì
ááááároutines«á  Yo⌡á ma∙ usσ LI┬ o≥ PLIB8╢ t∩ forφ theφá int∩á ß ì
ááááálibrar∙ iµ yo⌡ want«á  Notσ tha⌠ yo⌡ wil∞ havσ t∩ repea⌠ thσ ì
áááááinstallatioε procedurσ fo≥ ever∙ memor∙ mode∞ yo⌡ use«á  Oh¼ ì
áááááyes¼á yo⌡á caε deletσ thσ SOUNDTS╘ file≤ wheε yo⌡ arσá done¼ ì
áááááthougΦ thσ sourcσ give≤ ß gooΣ examplσ oµ thσ correc⌠ wa∙ t∩ ì
áááááacces≤ thσ library.

                          Ecosoft Notes

(1)ááThσá filσ SOUNDP.╚ i≤ provideΣ t∩ definσ thσá SounΣá Effect≤ ì
ááááácallablσá functions¼á usinτ thσ prototypσ form«á  Iµ yo⌡ arσ ì
áááááusinτá prototyping¼á thi≤á filσ shoulΣ bσá includeΣá iεá an∙ ì
ááááásource module that calls the Sound Effects library.

.paè.he SounΣ Effect≤                              Installatioε - Lattice

           Lattice C Version 2.14 or 2.15 Installation

Note║á Thσ ne≈ Latticσ compiler≤ (versioε 3.xx⌐ shoulΣ requirσ n∩ ì
       changσ t∩ thσ followinτ procedure.

Beforσá starting¼á se⌠á u≡á you≥ "worδ area"¼á whethe≥á i⌠á bσá ß ì
subdirectory on a hard disk, or a floppy disk.   Then ...

(1)á Cop∙á thσ .├ anΣ .╚ file≤ t∩ you≥ worδ diskettσ o≥ harΣ disδ ì
ááááásubdirectory«á  Cop∙á al∞ .AS╠ file≤ t∩ .AS═ file≤á oεá you≥ ì
áááááworδá area«á  Kee≡ thσ origina∞ distributioε disδ iε ßá safσ ì
áááááplace╗  all furthe≥ action≤ discusseΣ shoulΣ bσ donσ oε you≥ ì
áááááworδ area¼ no⌠ thσ distributioε disk.

(2)  Edi⌠á thσ filσ SOUND.╚ anΣ makσ surσ tha⌠ thσ onl∙á compile≥ ì
áááááflag set to 1 is C_LATTICE.

(3)ááCompilσá thσ ├ files«á  The∙ includσ thσ followinτ ╚á files¼ ì
áááááwhich should be included with your Lattice Compiler:

ááááá     STDIO.H     DOS.H

(4)ááAssemblσ thσ .AS═ file≤ usinτ thσ Microsof⌠ Macr∩á Assemble≥ ì
áááááo≥ equivalent«  Thσ filσ DOS.MA├ mus⌠ bσ present«  Thi≤ filσ ì
ááááái≤ includeΣ iε thσ Latticσ ├ packagσ anΣ allow≤ thσ assembl∙ ì
ááááámodulσs t∩ kno≈ thσ memor∙ mode∞ iε use.

(5)ááLinδá thσ filσ SOUNDTEST.OB╩ t∩ thσ res⌠ oµ .OBJ'≤á produceΣ ì
áááááb∙á thσá abovσá commands¼á anΣá t∩á thσá Latticσá ├á librar∙ ì
ááááá(LC.LIB).

(6)ááIµá yo⌡ hea≥ music¼á yo⌡ havσ correctl∙ installeΣ you≥ sounΣ ì
ááááároutines«á  Yo⌡á ma∙ usσ LI┬ o≥ PLIB8╢ t∩ forφ theφá int∩á ß ì
ááááálibrar∙ iµ yo⌡ want«á  Notσ tha⌠ yo⌡ wil∞ havσ t∩ repea⌠ thσ ì
áááááinstallatioε procedurσ fo≥ ever∙ memor∙ mode∞ yo⌡ use«á  Oh¼ ì
áááááyes¼á yo⌡á caε deletσ thσ SOUNDTS╘ file≤ wheε yo⌡ arσá done¼ ì
áááááthougΦ thσ sourcσ give≤ ß gooΣ examplσ oµ thσ correc⌠ wa∙ t∩ ì
áááááacces≤ thσ library.

                          Lattice Notes

(1)  Wheε compilinτ thσ SounΣ Effect≤ functions¼á bσ usurσ t∩ usσ ì
áááááthσá correc⌠á compile≥ flag≤ anΣ DOS.MA├ file¼á s∩ tha⌠á thσ ì
áááááSounΣá Effect≤ function≤ arσ usinτ thσ samσ memor∙ mode∞á a≤ ì
áááááyou≥ application«á  Yo⌡ ma∙ wan⌠ t∩ compilσ fou≥ version≤ oµ ì
áááááthe Sound Effects functions, one for each memory model.

(2)ááBσá surσá t∩ compilσ SounΣ Effect≤ function≤ usinτ thσá "-vó ì
ááááácompile≥ flaτ t∩ disablσ stacδ checking«  Thi≤ i≤ compatiblσ ì
áááááwitΦá thσá Latticσ library«á  No⌠ disablinτá stacδá checkinτ ì
ááááácoulΣ resul⌠ iε detectioε oµ ß bogu≤ "stacδ overflowó durinτ ì
áááááthσáá time≥á interrup⌠á handler'≤á execution«áá  Thi≤áá wil∞ ì
áááááterminate the application.
.paè.he SounΣ Effect≤                               Installatioε - Others


                     Non-Supported Compilers

T∩á usσá thσá SounΣ Effect≤ librar∙ witΦ ßá compile≥á othe≥á thaε ì
Latticσá o≥á Aztec¼á yo⌡á wil∞á havσ t∩á bσá familia≥á witΦá you≥ ì
compile≥á iε orde≥ t∩ customizσ thσ fe≈ assemble≥ routines«á  Thσ ì
followinτá question≤ shoulΣ bσ answereΣ first«á  Thσ answer≤á fo≥ ì
thσ supporteΣ compiler≤ arσ giveε fo≥ reference.


                                            Lattice  Manx  Yours?
                                            -------  ----  ------
 o Doe≤á you≥ compile≥ appenΣ o≥á prepenΣ ì
áááaεá underscorσá t∩á thσ namσá oµá eacΦ ì
áááfunction?                                   N      Y

 o Where does the compiler put parameters?   Stack   Stack

áo Wherσá doe≤á you≥ compile≥á placσá it≤ ì
áááreturn values for int?                     AX      AX
áááFor long int?                             AX,BX   DX,AX

áo Doe≤ you≥ compile≥ usσ nea≥ calls¼ fa≥ ì
ááácalls, or allows both?                    Both    Both

 o What provision does your library make     inp()  inport()
   for access to the I/O ports?             outp()  outport()


.paè.he Sound Effects                                 General Information

                        Using The Library

Usinτ thσ SounΣ Effect≤ librar∙ i≤ simila≥ t∩ usinτ thσá standarΣ ì
library'≤á I/╧ functions«á  Therσ i≤ aε "open"¼á somσ operations¼ ì
thσá ßá "close"«á  Iε thσ case¼á thσ openinτ functioεá i≤á calleΣ ì
sound_init(⌐ anΣ thσ closinτ functioε i≤ sound_done()«  Onσ poin⌠ ì
tha⌠á canno⌠á bσ stresseΣ overmucΦ i≤ thσ importancσá oµá callinτ ì
sound_done(⌐á beforσ exitinτ thσ program«á  An∙ applicatioε whicΦ ì
use≤á thσ sounΣ librar∙ shoulΣ cal∞ sound_done(⌐ a⌠ al∞á possiblσ ì
exi⌠ points.

Note the following things about sound_done():

     (1)á I⌠á neve≥á hurt≤ t∩ cal∞á it«á  Sound_done(⌐á know≤á iµ ì
áááááááááásound_init(⌐ ha≤ beeε called¼ anΣ act≤ accordingly.

ááááá(2)ááWheε calleΣ i⌠ wil∞ kil∞ an∙ musiπ stil∞ playing.

Thσ oppositσ numbe≥ oµ sound_done(⌐ i≤ sound_init()¼á wh∩á shoulΣ ì
(oµá course⌐ bσ calleΣ first¼á beforσ an∙ othe≥ sounΣá functions«  ì
I⌠á i≤ possiblσ t∩ ge⌠ awa∙ withou⌠ callinτ sound_init()¼á iµ yo⌡ ì
wan⌠ t∩ pla∙ iε modσ 1«á  Bu⌠ i⌠ reall∙ i≤ mucΦ neate≥ t∩ cal∞ i⌠ ì
anyway.

Wha⌠ i≤ modσ 1┐á  GlaΣ yo⌡ asked«á  Iε thσ play(⌐ function¼ therσ ì
i≤ ß MOD┼ sub-commanΣ whicΦ ha≤ t∩ d∩ witΦ ho≈ note≤ arσá played«  ì
Bu⌠á outsidσá oµ tha⌠ littlσ corner¼á wheε wσ sa∙ "modeóá wσá arσ ì
talkinτ abou⌠ theε WHE╬ anΣ HO╫ oµ thσ sounΣ output.

Yo⌡á go⌠á ßá tastσ oµ thσ meaninτ oµ mode≤ iε thσá discussioεá oµ ì
BackgrounΣá anΣá ForegrounΣá iεá thσáá introduction.áá  Real-timσ ì
programmers¼á forge⌠ you≥ usua∞ understandinτ oµ thesσ terms«  Iε ì
term≤á oµ thi≤ librar∙ musiπ playinτ iε ForegrounΣ play≤ wheε yo⌡ ì
tel∞á i⌠ to¼á anΣ you≥ applicatioε caε d∩ nothinτ elsσ unti∞á thσ ì
musiπ i≤ finished«á  Musiπ iε BackgrounΣ i≤ jus⌠ "se⌠ upó b∙ you≥ ì
commanΣ t∩ play¼á anΣ actuall∙ play≤ whilσ you≥ applicatioε runs«  ì
So¼á i⌠á i≤á "backgrounΣ musicó fo≥ thσá application¼á hencσá thσ ì
terminology«

Notσáá tha⌠áá thσáá term≤á musiπá anΣá sounΣá arσáá useΣáá rathe≥ ì
interchangeably«áá  Musiπá usinτá norma∞á note≤á i≤á mos⌠á easil∙ ì
generateΣá b∙á thσ play(⌐ function¼á whilσ sound(⌐ give≤á ßá morσ ì
flexiblσá interfacσ iµ yo⌡ arσ int∩á strangσá frequencies«á  BotΦ ì
function≤ caε operatσ iε ForegrounΣ anΣ Background.

.cp 12èTherσá arσá actuall∙ fivσ mode≤ iε whicΦ thσ sounΣá routine≤á caε ì
run«  Seσ thσ "Technica∞ Informationó sectioε fo≥ ß morσ completσ ì
descriptioε oµ thσ timinτ techniques«  Thσ defaul⌠ modσ i≤ 1.

  Mode      When          Timing Method
  ----   ----------    -------------------------
    1    Foreground    Delay Loop
    2    Foreground    Standard Clock Interrupt
    3    Foreground    Enhanced Clock Interrupt  (*)
    4    Background    Standard Clock Interrupt
    5    Background    Enhanced Clock Interrupt  (*)


Thσá modσ numbe≥ showε abovσ i≤ thσ valuσ yo⌡ shoulΣ givσ t∩á thσ ì
firs⌠ paramete≥ t∩ sound_init()«  Thσ seconΣ paramete≥ i≤ sueΣ a≤ ì
ßá true/falsσ flag¼á anΣ tell≤ sound_init(⌐ whethe≥ t∩ instal∞á ß ì
breaδ handler«á  Thσ breaδ handle≥ act≤ a≤ ß safet∙ feature╗á  i⌠ ì
make≤ surσ tha⌠ sound_done(⌐ i≤ calleΣ beforσ thσ applicatioεá i≤ ì
terminated by the user typing Control-C or Control-Break.

Iµá yo⌡ providσ you≥ owε breaδ handler¼á yo⌡ wil∞ wan⌠ t∩ disablσ ì
thσá built-iεá handler«á  Jus⌠ makσ surσ tha⌠ yo⌡á includeΣá tha⌠ ì
handle≥á iεá thσá lis⌠á oµá possiblσá exits¼á s∩á tha⌠á i⌠á call≤ ì
sound_done() before terminating the application.

Iµá yo⌡ don'⌠ havσ ß breaδ handle≥ buil⌠ iε t∩á thσá application¼ ì
let sound_init() put one in for you.

OK¼á no≈á  yo⌡á kno≈ tha⌠ you≥ applicatioε shoulΣ looδá somethinτ ì
like this:

     main()
     {
          sound_init(m,1);
          .
          .
          .
          sound_done();
     }

That'≤á prett∙á boring«á  Yo⌡ caε spicσ i⌠ u≡ afte≥á readinτá thσ ì
section≤á "Makinτá Musicó anΣ "Makinτ Noise"«á  Onσá morσá usefu∞ ì
functioε beforσ yo⌡ g∩ ..«á quiet()«á  Iµ yo⌡ se⌠ u≡ ß lonτ piecσ ì
oµá backgrounΣ music¼á anΣ fo≥ somσ reasoε havσ t∩ kil∞ i⌠á earl∙ ì
(bu⌠ no⌠ ge⌠ read∙ t∩ exit)¼á cal∞ quiet()«á  I⌠ ha≤ n∩ effec⌠ iε ì
ForegrounΣ modes.


                           ----------

     (*)  The enhanced modes currently produce the same
          results as the standard modes.  In a future
          version these modes will provide better time
          resolution.  See "Tech Tips" for details.
.paè.he Sound Effects                                        Making Music

                          Making Music
                          (Using Play)

Thσá pla∙ functioε translate≤ ß musica∞ scorσ int∩á sounds«á  Thσ ì
scorσ i≤ writteε usinτ ß specia∞ notatioε describeΣ below«á  Thi≤ ì
notatioεá allow≤á thσá usσ oµ ╕ octave≤ oµ 1▓á note≤á each¼á witΦ ì
various tempos, etc.  The format of pla() is:

     void play(m)
     char *m;

Command≤ arσ ß singlσ lette≥ followeΣ immediatel∙ b∙ onσ o≥á morσ ì
arguments¼á iµá necessary«á  Spaces¼á commas¼á anΣ semicolon≤ ma∙ ì
appea≥ betweeε command≤ fo≥ clarity¼ bu⌠ arσ ignoreΣ b∙ play().


Aáto G:   Thesσ arσ thσ note≤ ┴ througΦ G¼ iε thσ curren⌠ octave«  ì
áááááááááá┴á notσá ma∙ bσ followeΣ b∙ u≡ t∩ threσá modifiers¼á iε ì
ááááááááááthi≤ orde≥ only:

áááááááááá     Sharp/Fla⌠ indication║  ú o≥ ½ i≤ sharp;
áááááááááá                             - i≤ flat.
áááááááááá     Notσ length║  numbe≥ froφ ▒ t∩ 6┤ (seσ L)
áááááááááá     Dots║ U≡ t∩ 10 dots.  A dotted note plays for 3/2
                     of it's normal time.  Two dots = 9/4, three
                     dots = 27/8, etc.

ááááááááááExamplσs (assuminτ thσ curren⌠ notσ lengtΦ i≤ 4):

áááááááááá     C+        C sharp 1/4 note
áááááááááá     C+8       C sharp 1/8 note
áááááááááá     B-«       ├ shar≡ 1/┤ notσ dotteΣ ╜ 3/╕ note
áááááááááá     A2.       A 1/2 note dotted = 3/4 note


LnááááááááSet≤ thσ curren⌠ notσ length«  Notσ lengtΦ i≤ 1/n¼ s∩ ß ì
ááááááááááparamete≥á oµ ┤ wil∞ se⌠ subsequen⌠ notσ t∩ 1/┤á notes«  ì
ááááááááááIndividua∞á note≤ ma∙ overridσ thσ curren⌠ lengtΦá witΦ ì
ááááááááááaε explici⌠ lengtΦ (seσ abovσ examples)«á  Thσ rangσ i≤ ì
áááááááááá▒ t∩ 64.

ááááááááááNotσá lengtΦá combine≤á witΦá temp∩á t∩á determinσá thσ ì
ááááááááááduratioε oµ thσ note«  LengtΦ i≤ measureΣ a≤ ß fractioε ì
ááááááááááoµá ß wholσ note¼á whilσ temp∩ i≤ iε quarter-note≤á pe≥ ì
áááááááááásecond«á  Fo≥á example¼á witΦ ß temp∩ oµ 3▓ anΣ ßá notσ ì
áááááááááálengtΦ oµ 2¼ ß notσ wil∞ las⌠ fo≥ 1/1╢ oµ ß second.

.cp 10èMxááááááááSets the mode of the music.  There are three modes:

áááááááááá   x=Ná(NORMAL)║á  note≤ arσ playeΣ fo≥ 7/╕ oµ thσ notσ ì
ááááááááááááááááátime¼ witΦ thσ remaininτ 1/╕ beinτ ß rest.

áááááááááááááx=Sá(STACCATO)║ note≤ arσ playeΣ fo≥ 3/┤ oµ thσ notσ ì
ááááááááááááááááátime¼ witΦ thσ remaininτ 1/┤ beinτ ß rest.

áááááááááááááx=L (LEGATO)║á note≤á arσ playeΣ fo≥ thσá ful∞á notσ ì
ááááááááááááááááátime¼ witΦ n∩ rest.

          Thσ mode≤ ForegrounΣ anΣ BackgrounΣ havσ nothinτ t∩á d∩ ì
ááááááááááwitΦ thesσ mode≤ !

Nná       Play≤ notσ ε (rangσ 0..84)¼á wherσ ░ mean≤ silence«  Iµ ì
ááááááááááthσá argumen⌠ i≤ missinτ o≥ ou⌠ oµ range¼á n∩á notσá i≤ ì
ááááááááááplayed.  Cannot be dotted or given explicit length.

OnááááááááSet≤ octavσ t∩ ε (rangσ 0..7)«á  Iµ argumen⌠ i≤ ou⌠á oµ ì
áááááááááárange, current octave remains unchanged.

P[n][.]áááPausσ o≥ rest╗á  seσ thσ rule≤ fo≥ notσ lengtΦ (n⌐á anΣ ì
áááááááááádottinτá fo≥á thσá regula≥ note≤á A-╟á above«á  Iµá thσ ì
ááááááááááargument is missing or invalid, no pause takes place.

RáááááááááResets to default values.  Resets the following:
áááááááááá          Octave = 4
áááááááááá          Length = 1
áááááááááá          Mode = Normal
áááááááááá          Tempo = 120

TnááááááááTempo¼á whicΦá ma∙ rangσ froφ 3▓ t∩ 255¼á control≤á thσ ì
áááááááááánumbe≥á oµ quarter-note≤ pe≥ second«á  Thσá defaul⌠á i≤ ì
áááááááááá120.

<áááááááááMove≤ dowε onσ octave«á  Iµ alread∙ a⌠ octavσ 0¼á stay≤ ì
ááááááááááthere.

>áááááááááMove≤á u≡ onσ octave«á  Iµ alread∙ a⌠ octavσá 7¼á stay≤ ì
ááááááááááthere.


.paè.he Sound Effects                                        Making Noise

                          Making Noise
                    (Using Sound and Sounds)

Thσá functioεá sound(⌐ anΣ sounds(⌐ allo≈ thσ prograφ t∩á producσ ì
sound≤ othe≥ thaε thosσ oε thσ norma∞ musica∞ scale«  Thσ penalt∙ ì
fo≥á thi≤ flexibilit∙ i≤ tha⌠ morσ worδ i≤ usuall∙á requireΣá  t∩ ì
specif∙ thσ frequenc∙ anΣ duratioε oµ eacΦ sound¼ especiall∙ wheε ì
forming complex noises.

T∩á producσ ß singlσ sound¼á cal∞á sound()«á  Simple¼á eh┐á  Jus⌠ ì
providσá thσá frequenc∙á a≤á (H· ¬ 100)¼á anΣá thσá duratioεá iε ì
milliseconds«á  T∩ producσ ß serie≤ oµ sounds¼á yo⌡ caε se⌠ u≡ aε ì
arra∙á oµá structure≤á oµ thσ typσ sound_elemen⌠ anΣ pas≤á i⌠á t∩ ì
sounds()¼á alonτá witΦ ß coun⌠ oµ thσ numbe≥ oµá elements«á  EacΦ ì
elemen⌠á take≤ u≡ si° bytes╗á fou≥ byte≤ fo≥ thσ frequenc∙á (lonτ ì
int⌐ anΣ tw∩ fo≥ thσ duratioε (unsigned).

.paè.he SounΣ Effect≤                               Functioε Descriptions

                      Summary Function List

Thesσá function≤á arσ describeΣ iε detai∞ later¼á bu⌠ herσá i≤á ß ì
comprehensivσ lis⌠ oµ thσ function≤ iε thσ library¼ witΦ thσ filσ ì
locatioε anΣ ß shor⌠ descriptioε oµ eacΦ one.


                           High-Level

sound_init   SOUNDCTL    Call to set mode, etc.
sound_done   SOUNDCTL    Call before exit.
sound_modeáááSOUNDCTLáá  Returns current mode.
sound     áááSOUNDáá     Make a noise.
sounds    áááSOUNDáá     Make several noises.
pla∙         PLAY        Makσ pleasan⌠ noise≤ usinτ eas∙ notation.
quiet     áááSOUNDOUTáá  Kill playing background music.
sound_bchk   SOUNDOUT    Check status of sound buffer.

                            Low-Level

spkr_on   áááSPKRCTLáá   Speaker on  (continuous noise)
spkr_off  áááSPKRCTLáá   Speaker off (blissful quiet)
spkr_freq áááSPKRCTLáá   Sets the frequency of the noise
spkr_cnt≥    SPKRCTL     Set≤ frequenc∙ als∩ (seσ funπ description)

                     Internal --- DO NOT USE

sound_out    SOUNDOUT    Interrupt-driven output routine
snd_irh      SOUNDINT    Assembly interface for sound_out
snd_brk      SOUNDINT    Built-in break handler
snd_giv      SOUNDINT    Utility - get interrupt vector
snd_siv      SOUNDINT    Utility - set interrupt vector
delay        DELAY       Internal delay loop used in mode 1
.paè                      SOUND_INIT and SOUND_DONE

Purpose:

áááááSe⌠ u≡ anΣ tea≥ dowε thσ interrup⌠ vector≤ needeΣ t∩ providσ ì
ááááásound.

Summary:

     int sound_init(mode,install_bh)
áááááint mode, install_bh;

áááááint sound_done();

Parameters:

áááááMode:     áááááMus⌠ bσ iε thσ rangσ 1..5╗  set≤ thσ modσ fo≥ ì
áááááááááááááááááááásubsequen⌠áá call≤á t∩á sound(⌐á anΣá play()«  ì
ááááááááááááááááááááValues are:

                     1  Foreground w/ Delay Loop
                     2  Foreground w/ Standard Clock Interrupt
                     3  Foreground w/ Enhanced Clock Interrupt
                     4  Background w/ Standard Clock Interrupt
                     5  Background w/ Enhanced Clock Interrupt

áááááInstall_bh:á   Iµá thi≤á i≤á 0¼á n∩á break-handle≥á wil∞á bσ ì
ááááááááááááááááááááinstalled«á  Otherwise¼á ß breaδ handle≥ wil∞ ì
áááááááááááááááááááábσ installed«á  Seσ Technica∞ Informatioε fo≥ ì
ááááááááááááááááááááß completσ descriptioε oµ thσ breaδ handler.

Returns:

     Zer∩á indicate≤ success«á  Sound_ini⌠ wil∞ returε -▒á iµá aε ì
áááááinvaliΣ modσ i≤ passed.

Notes:

áááááSound_init(⌐á ma∙á bσ calleΣ morσ thaε oncσ withou⌠á harmfu∞ ì
áááááeffects«á  Wheε called¼á an∙ musiπ currentl∙ playinτ wil∞ bσ ì
ááááákilled«á  Yo⌡ caε usσ call≤ t∩ sound_init(⌐ t∩ changσá mode≤ ì
ááááádurinτ thσ application.

áááááSound_done(⌐ shus⌠ ofµ backgrounΣ musiπ anΣ thσ speaker¼ anΣ ì
áááááclean≤á u≡ an∙ interrup⌠ vector≤ whicΦ ma∙ havσ beeε changeΣ ì
áááááb∙ sound_init()«  Thi≤ let≤ thσ applicatioε safel∙ exit.

.paè                           SOUND_MODE

Purpose:

áááááReturn≤á thσ curren⌠ sounΣ mode«á  Seσ sound_init(⌐ fo≥á thσ ì
ááááápossible values.

Summary:

     int sound_mode()

Parameters:

áááááNone

Returns:

     Return≤áá curren⌠á mode¼áá rangσá 1-5«áá  Seσáá sound_init(⌐ ì
ááááádescription for complete list of modes.

.paè                        SOUND  &  SOUNDS

Purpose:

     Producσ ß sounΣ o≥ sound≤ fo≥ ß certaiε time.

Summary:

     void sound(freq,dur)
     long freq;
     unsigned dur;

ááááávoid sounds(n,sa)
áááááint n;
ááááástruct sound_desc *sa;ááááá

Parameters:

     freq:  Frequenc∙ iε MH· ¬ 10«á  Ex║ 400MH· passeΣ a≤ 40000L«  ì
ááááááááááááThσá allowablσá rangσ i≤ ???«á  ┴ frequenc∙ oµá ░á i≤ ì
áááááááááááátreateΣá a≤ "silence"«á  ┴ sounΣ witΦ ß duratioε oµ ░ ì
ááááááááááááis ignored.

     dur:   Duration of sound in milliseconds.

ááááán:     Numbe≥ oµ sound≤ passed«á  Number≤ les≤ thaε zer∩ arσ ì
áááááááááááátreated as zero.

ááááása:á   Arra∙á oµá sounΣá descriptions¼áá eacΦá containinτá ß ì
ááááááááááááfrequenc∙á anΣ ß duration¼á a≤ pe≥ thσ fre±á anΣá du≥ ì
ááááááááááááparameter≤ passeΣ t∩ sound.

Returns:

     0 if all parameters all OK
    -1 if error in parameters (out of range).

Error Handling:

     Checks parameter range only.

Notes:

áááááThesσá function≤á arσ effecteΣ b∙ thσ modσ currentl∙ se⌠á b∙ ì
áááááthσá mos⌠ recen⌠ cal∞ t∩ sound_init«á  The∙ ma∙ bσ useΣá fo≥ ì
áááááeither foreground or background operation.

.paè                              PLAY

Purpose:

     Pla∙ ß serie≤ oµ musica∞ note≤ usinτ aε eas∙ notation.

Summary:

     void play(music)
     char *music;

Parameters:

áááááThσá musiπá paramete≥á i≤ ß strinτ whicΦá caεá contaiεá man∙ ì
ááááácomple°á operations¼á al∞á oµá whicΦ arσá describeΣá iεá thσ ì
ááááásection "Making Music".

Returns:

     Nothing.

Error Handling:

áááááAn∙á problem≤ encountereΣ iε thσ musiπ strinτ arσ handleΣ a≤ ì
ááááádescribeΣ iε thσ section "Making Music."

Notes:

     Thσá pla∙ functioε introduce≤ aε amoun⌠ oµ overheaΣ iε term≤ ì
áááááoµ codσ size¼á a≤ i⌠ mus⌠ parsσ thσ string«  ┴ prograφ whicΦ ì
ááááái≤á memory-critica∞á shoulΣ usσá sounds()╗á  oµá coursσá thσ ì
áááááprogramme≥á mus⌠á theε perforφ thσ tasδ oµá convertinτá eacΦ ì
ááááánotσ int∩ onσ o≥ morσ sounds«

áááááSee "Making Music" for details on play()'s operation.
ì
.paè                DIRECT SPEAKER CONTROL FUNCTIONS

Purpose:

     Direct control of speaker port.

Summary:

     void spkr_on()

ááááávoid spkr_off()

ááááávoid spkr_freq(f)
ááááálong f;

ááááávoid spkr_cntr(c)
áááááunsigned c;

Parameters:

áááááThσá paramete≥á t∩ spkr_fre± i≤ thσ frequenc∙ iε MH· t∩á se⌠ ì
áááááthσá speake≥ to«á  Thσ paramete≥ t∩ spkr_cnt≥ i≤ thσá actua∞ ì
ááááácounte≥á valuσ t∩ bσ passeΣ t∩ thσ 825│á time≥á chip«á  Notσ ì
ááááátha⌠á thσ onl∙ function≤ t∩ actuall∙ turε thσ speake≥ oεá o≥ ì
áááááofµá arσ spkr_oε anΣ spkr_off╗á  settinτ thσ frequenc∙á doe≤ ì
ááááánot imply activating or deactivating the speaker.ì

Returns:

áááááNothing.

Error Handling:

     None.

Notes:

     Unlikσ sound()¼á sounds()¼á anΣ play()¼á whicΦ caε bσ freel∙ ì
áááááintermixed¼á usσá oµá thesσá low-leve∞á function≤á whilσá iε ì
ááááábackgrounΣá modσá caε disrup⌠ thσ backgrounΣá music«á  Whilσ ì
áááááthi≤á i≤ fa≥ froφ fatal¼á i≤ caε producσ unpleasan⌠á noises«  ì
áááááCal∞ quiet(⌐ beforσ usinτ thesσ functions.

.paè
                   BACKGROUND-BUFFER FUNCTIONS

Purpose:

     Control music playing in background.

Summary:

     void quiet()

ááááávoid sound_bchk(used,avail)
áááááint *used, *avail;

Parameters:

áááááquite:              none.

ááááásound_buffchk():    used to return values (see below).

Returns:

áááááquiet() has no return value.

ááááábuffchk(⌐ return≤ thσ numbe≥ oµ sounΣ element≤ iε thσ buffe≥ ì
áááááanΣ thσ numbe≥ oµ freσ elements¼á viß thσ parameter≤á "usedó ì
áááááanΣ "availó respectively.

Error Handling:

áááááNone.

Notes:

     ┴á cal∞ t∩ quie⌠ wil∞ kil∞ an∙ backgrounΣ music¼á flusΦá thσ ì
ááááábuffer¼ anΣ shu⌠ ofµ thσ speaker«

.paè.he Sound Effects                               Technical Information

                     =======================
                      TECHNICAL INFORMATION
                     =======================

╔á havσ trieΣ t∩ bσ clea≥ anΣ precisσ iε thesσá technica∞á notes«  ì
ShoulΣá yo⌡á finΣ an∙ error≤ iε codσ o≥á documentation¼á o≥á havσ ì
suggestion≤ fo≥ improvement¼á  ╔ woulΣ appreciatσ you≥á feedback«  ì
Thesσá paragraph≤á arσá no⌠ fo≥ thσ fain⌠á oµá heart«á  Fo≥á morσ ì
details¼á ╔á sugges⌠ somσ oµ Pete≥ Norton'≤  excellen⌠ P├á books¼ ì
anΣ thσ ever-cryptiπ bu⌠ fact-filleΣ IB═ Technica∞ Reference.

Here is a brief summary of this section:


     Timing Sound Duration (MODES)
        Delay Loop - How, Pro & Con
        Timer Interrupt - How, Pro & Con
        Enhanced Interrupt - How, Pro & Con

     Sound Generation Mechanics
        Speaker Logic
        Setting The Frequency

     The Background Buffer

     The Break Handler

     The Interrupt Handler


                    =========================
                    TIMING THE SOUND DURATION
                    =========================

Therσá arσ fivσ mode≤ iε whicΦ thσ sounΣ routine≤ caε run«á  The∙ ì
definσá WHE╬á thσ musiπ plays¼á anΣ ho≈ thσá prope≥á DURATIO╬á i≤ ì
determined«  Thσ FREQUENC┘ oµ thσ sound≤ i≤ alway≤ determineΣ anΣ ì
produceΣ b∙ thσ samσ methoΣ regardles≤ oµ mode¼á anΣ i≤ describeΣ ì
ß fe≈ paragraph≤ below.

  Mode   When          Timing
  ----   ----          ------
    1    Foreground    Delay Loop
    2    Foreground    Standard Clock Interrupt
    3    Foreground    Enhanced Clock Interrupt
    4    Background    Standard Clock Interrupt
    5    Background    Enhanced Clock Interrupt

Thσá defaul⌠ modσ i≤ modσ 1«á  I⌠ pose≤ thσ fewes⌠ problems¼á bu⌠ ì
ha≤ somσ limitations«  Thσ timinτ i≤ achieveΣ usinτ ß dela∙ loop¼ ì
whicΦá i≤á simpl∙á ß smal∞ piecσ oµ codσ witΦ ßá knowεá executioε ì
time«á  B∙ loopinτ througΦ thi≤ piecσ oµ codσ yo⌡ caε approximatσ ì
thσ duratioε oµ thσ sound≤ fairl∙ well«á
èUnfortunately¼á thσá dela∙ loo≡ methoΣ ha≤ problems«á  I⌠ i≤ ver∙ ì
dependen⌠ oε thσ hardware, for one thing«á  ┴ processo≥á runninτ ì
a⌠á 8MH·á wil∞á executσ thσ codσ iε closσ t∩ halµ thσ timσá oµá ß ì
standarΣá P├ runninτ a⌠ 4.77MHz¼á s∩ thσ sound≤ wil∞ bσá shorter«  ì
Also¼ thσ timinτ become≤ dependen⌠ oε processo≥ type«  Thσ norma∞ ì
PC has an 8088;  oε aεá AT&╘ 6300  (8086) o≥ oε a PC-A╘ (80286),ì
therσá wil∞ bσ ß noticeablσ timinτ differencσ duσ t∩ thσá varyinτ ì
bu≤ width≤ anΣ executioε speeds¼ eveε iµ thσ basσ processo≥ clocδ ì
speeΣ wa≤ thσ same«á  AnΣ a≤ thσ coup-de-grace¼á thi≤ methoΣ wil∞ ì
bσ throwε ofµ b∙ thσ occurancσ oµ interrupts«á  Aε interrup⌠ wil∞ ì
causσá othe≥ codσ t∩ bσ executeΣ whicΦ wil∞ extenΣ thσá executioε ì
timσ oµ thσ loop.

Fortunatel∙ therσ i≤ ß bette≥ timinτ methoΣ available«á  Therσ i≤ ì
aεá on-boarΣ maiε systeφ clocδ chi≡ whicΦ provide≤ ß pulsσ witΦ ß ì
frequenc∙á oµ abou⌠ 1.19MHz«á  Thi≤ i≤ steppeΣ dowε t∩á ßá morσ ì
reasonablσ ratσ b∙ thσ 825│ counte≥ chip«á  Thσ mos⌠ familia≥ usσ ì
oµá thi≤ i≤ t∩ providσ thσ systeφ tick¼á whicΦ occur≤ 18.▓ timσ ß ì
seconΣ anΣ generate≤ thσ hardwarσ clocδ interrup⌠ (IRQ0¼á IN╘ 8)«  ì
Thi≤á i≤á generall∙á independen⌠á oµá thσá clocδá speeΣá oµáá thσ ì
processor¼á anΣ s∩ i≤ ß gooΣ timinτ sourcσ acros≤ thσ extendeΣ P├ ì
family.

Wσ caε usσ thi≤ systeφ ticδ t∩ timσ thσ sounds«á  BotΦ foregrounΣ ì
anΣá backgrounΣ method≤ caε d∩ this╗á  thσ foregrounΣ mode≤á wil∞ ì
merel∙á wai⌠á arounΣá unti∞ thσ sounΣá i≤á over«á  Thereforσá thσ ì
followinτá discussion≤á oµ thσ usσ oµ thσ systeφá ticδá interrup⌠ ì
appl∙ t∩ botΦ foregrounΣ anΣ background.

Thσá standarΣá interrup⌠ mode≤ (▓ anΣ 4⌐ tiσá int∩á thσá softwarσ ì
interrup⌠á vecto≥á 0x1C«á  Thi≤á i≤ thσá "use≥á time≥á interruptó ì
vector¼ anΣ i≤ provideΣ b∙ thσ BIO╙ a≤ ß nicσ wa∙ t∩ tiσ softwarσ ì
int∩áá thσá timer«áá  Thσá BIO╙á interrup⌠á handle≥á retain≤á al∞ ì
responsibilit∙á fo≥ handlinτ thσ mess∙ task≤ oµá sendinτá end-of-ì
interrup⌠á t∩á thσ interrup⌠ controlle≥á chip¼á incrementinτá thσ ì
time-of-da∙á clocδ tick¼á etc«á  Thi≤ i≤ ß cleaε wa∙ t∩á usσá thσ ì
system tick to time events.

                        Possible Problems

Therσá arσá onl∙ tw∩ possiblσ problem≤ (tha⌠ ╔ caε see⌐ t∩á usinτ ì
thσá systeφá tick«á  Onσá i≤ tha⌠ somσá memory-residen⌠á softwarσ ì
package≤á arσ ver∙ possessivσ abou⌠ interrupts«á  Tha⌠ i≤ wh∙á s∩ ì
man∙ oµ theφ arσ incompatiblσ witΦ eacΦ other«á  Iεá theory¼á an∙ ì
numbe≥á oµá driver≤ coulΣ sharσ thσ use≥ systeφ ticδ b∙á chaininτ ì
themselve≤ together¼á bu⌠ the∙ ofteε don't«á  Thi≤ softwarσ does¼ ì
s∩ i⌠ wil∞ worδ witΦ well-behaveΣ utilities.

Thσ othe≥ probleφ mainl∙ involve≤ backgrounΣ mode«á  Iµ thσá use≥ ì
abort≤ thσ prograφ b∙ usinτ contro∞ Ctrl-Break¼ interrup⌠ vector≤ ì
wil∞á no⌠ bσ restored¼á anΣ eventuall∙ thσ systeφ wil∞ crasΦá anΣ ì
neeΣá rebooting«á  Thi≤á caε bσ preventeΣ b∙ usinτá thσá provideΣ ì
breaδ handle≥ (seσ SOUND_INIT⌐ o≥ b∙ callinτ sound_done(⌐ iµ you≥ ì
applicatioε alread∙ provide≤ it≤ owε breaδ handler.
è                         Enhanced Modes

Thσá enhanceΣá interrup⌠á mode≤á (│ anΣá 5⌐á arσá no⌠á ye⌠á full∙ ì
implemented¼á anΣá arσá presentl∙á thσá samσ a≤á mode≤á ▓á anΣá ┤ ì
respectively«á  Iε ß futurσ release¼ the∙ wil∞ follo≈ thσ examplσ ì
oµá BASI├ anΣ changσ thσ systeφ ticδ generatioε t∩ providσ bette≥ ì
resolution«á  Thi≤ ticδ i≤ speΣ u≡ b∙ ß facto≥ oµ 4«á  Thσá sounΣ ì
systeφá mus⌠ intercep⌠ thi≤ ticδ a⌠ thσ IN╘ ╕ level¼á anΣ providσ ì
thσ ticδ t∩ thσ BIO╙ onl∙ ever∙ fourtΦ time¼á t∩ kee≡ thσá systeφ ì
time-of-da∙á clocδ froφ speedinτ ahead«á  Thσ advantagσ i≤ bette≥ ì
timσ resolution.

Thσá disadvantage≤ t∩ thσ enhanceΣ mode≤ includσ al∞ oµ thσá one≤ ì
giveε fo≥ thσ standarΣ clocδ modes¼ plu≤ thσ codσ ha≤ t∩ diτ eveε ì
deepe≥á int∩á territor∙á wherσá application≤á program≤á arσáá no⌠ ì
encourageΣá t∩á venture«á  Still¼á takinτ prope≥ carσ t∩á restorσ ì
vector≤ upoε exit¼á thi≤ shoulΣ bσ cleaε enougΦ fo≥ everyda∙ use«  ì
Therσ i≤ ß questioε a≤ t∩ thσ valuσ oµ thσ morσ precisσ timinτ oµ ì
thσ sounds¼ whicΦ ma∙ no⌠ bσ oµ grea⌠ importancσ anyway.


                   ==========================
                   SOUND GENERATION MECHANICS
                   ==========================

                          Speaker Logic

Thσá sound≤á arσ produceΣ usinτ thσ speake≥ attacheΣ t∩á thσá IB═ ì
motherboard«á  Thσá speake≥á i≤ pulseΣ t∩ providσá sounΣá oµá thσ ì
desireΣá frequency«á  Thσ pulsinτ actioε i≤ provideΣ courtes∙á oµ ì
thσáá maiεáá systeφá clock¼áá steppeΣá dowεá througΦáá thσáá 825│ ì
programmablσ counter«  Therσ i≤ als∩ aε on/ofµ switcΦ provideΣ b∙ ì
ßá bi⌠á iεá thσá PP╔ chip«á  Thσá speake≥á contro∞á circuitr∙á i≤ ì
logicall∙ (no⌠ electrically⌐ diagrammeΣ as:

    +-------+    +--------+
    | 8284A |--->| 8253-5 |----+
    +-------+    +--------+    |    ____               /|
                               +--> )   \             / |
                                    |AND >---------->[  |
                               +--> )___/             \ |
              +-----+          |                       \|
              | PPI |----------+
              +-----+                                Speaker

Thσá PP╔ switcΦ i≤ accesseΣ a≤ bit≤ ░ anΣ ▒ a⌠ I/╧ addres≤á 0x61«  ì
Wheε thσ bit≤ arσ se⌠ thσ speake≥ switcΦ i≤ on¼á wheε cleareΣ thσ ì
speake≥á switcΦá i≤á off«áá  Seσá thσá spkr_on(⌐á anΣá spkr_off(⌐ ì
function≤ t∩ seσ ho≈ t∩ d∩ thi≤ froφ C«á  Notσ tha⌠ thσ valuσá oµ ì
thσá PP╔á i≤á firs⌠ read¼á thσ requireΣ bit≤á changed¼á anΣá theε ì
writteεá out«á  Thi≤ i≤ necessar∙ becausσ thσ PP╔ ha≤ man∙á othe≥ ì
use≤ fo≥ thσ res⌠ oµ thσ bits.

.cp 6è                Setting Frequency using the 8253

Thσáá systeφá clocδá oscillate≤á a⌠á abou⌠á 1.19MHz«áá  Thσá 825│ ì
programmablσ counte≥ step≤ dowε thi≤ frequenc∙ b∙ sendinτ ß pulsσ ì
fo≥á ever∙ s∩ man∙ inpu⌠ pulses«á  Thσ well-knowε systeφ ticδá oµ ì
18.▓á tick≤ pe≥ seconΣ i≤ obtaineΣ usinτ thi≤ chi≡ anΣ ßá diviso≥ ì
oµ 0xFFFF«  Thσ chi≡ ha≤ tw∩ counters╗  whilσ onσ outpu⌠ connect≤ ì
t∩á thσ systeφ clocδ interrupt¼á thσ othe≥ tie≤ t∩á thσá speaker«  ì
So¼á b∙á changinτ thσ diviso≥ iε thσ counter¼á wσ caε changσá thσ ì
frequenc∙á oµá thσá pulse≤á sen⌠ t∩ thσá speake≥á anΣá hencσá thσ ì
frequenc∙ oµ thσ sounΣ i⌠ produces.

Fo≥á morσá detail≤ oε thσ usσ oµ thσ 825│á programmablσá counter¼ ì
consult the Intel part spec.


                      =====================
                      THE BACKGROUND BUFFER
                      =====================

Sound≤á t∩ bσ playeΣ iε mode≤ ▓ througΦ ╡ arσ placeΣ iε ßá buffe≥ ì
anΣá playeΣá unde≥ interrup⌠ control«á  Sincσ thi≤ buffe≥á i≤á oµ ì
finitσ size¼ i⌠ i≤ possiblσ t∩ overflow«  Overflowinτ sound≤ wil∞ ì
bσ discarded.

EacΦ entr∙ take≤ u≡ fou≥ (4⌐ bytes¼á anΣ thσ numbe≥ oµ entrie≤ iε ì
thσá buffe≥á i≤ fixeΣ wheε yo⌡ builΣ thσ library«á  Thσá compileΣ ì
file≤ oε thσ disδ havσ ß defaul⌠ buffe≥ sizσ oµ 6┤ entries«á  Yo⌡ ì
caεáá changσá thi≤á b∙á changinτá thσá valuσá oµáá thσáá constan⌠ ì
SND_BUFFSIZ┼ iε SOUND.╚ anΣ recompilinτ thσ system.

EacΦá notσ sen⌠ t∩ play(⌐ wil∞ usuall∙ generatσ tw∩ entries¼á onσ ì
fo≥ thσ notσ anΣ onσ fo≥ thσ inter-notσ pause«  Usinτ sound(⌐ anΣ ì
sounds(⌐ wil∞ generatσ exactl∙ onσ entr∙ pe≥ sounΣ element.

Thσá sounΣ buffe≥ i≤ circular¼á s∩ tha⌠ a≤ entrie≤ arσ outpu⌠á t∩ ì
thσ speaker¼á morσ caε bσ added«á  Checδ thσ statu≤ oµ thσ buffe≥ ì
usinτ thσ functioε sound_bchk()¼á whicΦ wil∞ ge⌠ yo⌡ botΦá thσ ì
numbe≥ oµ entrie≤ useΣ anΣ thσ numbe≥ oµ entrie≤ free.


                       ===================
                        THE BREAK HANDLER
                       ===================

Thσá built-iεá breaδ handle≥ ha≤ ß simplistiπ vie≈ oµá life«á  I⌠ ì
accept≤á control¼á call≤ sound_done(⌐ t∩ cleaεá up¼á theεá passe≤ ì
contro∞á t∩ thσ breaδ handle≥ tha⌠ precede≤ it«á  Thi≤ mean≤ tha⌠ ì
thσ usua∞ ne⌠ resul⌠ i≤ aε exi⌠ t∩ DOS¼ bu⌠ safely«  Fee∞ freσ t∩ ì
usσá thσá giveε functioε a≤ ß template¼á bu⌠á kee≡á thσá origina∞ ì
arounΣ iε casσ yo⌡ accidentall∙ mucδ i⌠ u≡ ß bit.

.cp 15è                     =======================
                      THE INTERRUPT HANDLER
                     =======================

Thi≤á refer≤á  t∩á thσ time≥ interrup⌠á handler¼á ßá ver∙á simplσ ì
routine«á  It≤á joΓ i≤ t∩ savσ thσ registers¼á loaΣá thσá segmen⌠ ì
register≤ tha⌠ ├ function≤ expect¼ cal∞ sound_out(⌐ t∩ d∩ al∞ thσ ì
work¼á anΣ restorσ al∞ thσ registers«á  I⌠ theε call≤ thσ routinσ ì
whicΦá wa≤á previousl∙á thσ interrup⌠ handler«á  Thi≤ i≤á ßá nicσ ì
courteou≤á thinτá t∩ do¼á a≤ i⌠ allow≤ sharinτ oµá thi≤á valuablσ ì
resource¼ thσ systeφ tick.


.paè                      WHEN THINGS GO WRONG

Firs⌠ oµ all¼á pleasσ fee∞ freσ t∩ asδ mσ (thσ author⌐ questions«  ì
╔ canno⌠ accep⌠ phonσ question≤ a⌠ thi≤ time¼ mainl∙ becausσ ╔ aφ ì
no⌠á nea≥ an∙ particula≥ phonσ durinτ thσ day«á  Yo⌡ caε reacΦ mσ ì
b∙ mai∞ o≥ b∙ CompuServσ EASYMAI╠ (73047,3715)«á  Bu⌠ first¼á seσ ì
iµ thσ followinτ lis⌠ ha≤ you≥ probleφ oε it.


"I cannot read the distribution disk."

     Thσá distributioεá disδ i≤ provideΣ iε IB═á double-sideΣá 9-ì
ááááásecto≥ format«  Yo⌡ wil∞ no⌠ bσ ablσ t∩ reaΣ i⌠ witΦ single-ì
ááááásideΣ drive≤ o≥ witΦ ß DO╙ versioε beforσ 2.0.

áááááIµ yo⌡ caε reaΣ sucΦ disk≤ normally¼á therσ i≤ ß chancσ tha⌠ ì
áááááthσ diskettσ ha≤ beeε damageΣ iε transit«  Pleasσ returε thσ ì
ááááádiskette and you will get another copy, no charge.


"The files will not compile on my system."

áááááIµá yo⌡ arσ usinτ ß non-supporteΣ compiler¼á al∞ ╔ caε d∩ i≤ ì
ááááárefe≥ yo⌡ t∩ thσ sectioε oε Settinτ U≡ fo≥ Othe≥ Compilers"«  ì
áááááIµá yo⌡á d∩á ge⌠á everythinτ working¼á eveεá iµá jus⌠á oεá ß ì
ááááádifferen⌠á versioεá oµá Latticσá o≥á Manx/Aztec¼áá ╔áá woulΣ ì
áááááappreciatσá iµ yo⌡ le⌠ mσ know«á  ╔ wil∞ d∩ everythinτ ╔ caε ì
ááááát∩ hel≡ yo⌡ ge⌠ i⌠ compileΣ anΣ running¼á bu⌠ withou⌠ ß cop∙ ì
áááááoµá thσá compile≥ (D╧ NO╘ SEN─ M┼á COPYRIGHTE─á SOFTWARE⌐á ╔ ì
ááááácannot promise much.

áááááBσá surσá yo⌡ havσ thσ filσ SOUND.╚ wherσ you≥ compile≥á caε ì
áááááfinΣá it«á  Als∩ bσ surσ tha⌠ yo⌡ havσ enougΦ rooφá oεá you≥ ì
ááááádiskettes for the compiler's output.

"My system locks up when I run a program using sound."

áááááFirst¼á iµ yo⌡ havσ an∙ memory-residen⌠ utilities¼ let'≤ ge⌠ ì
áááááriΣá oµ theφ fo≥ thσ moment«á  De-instal∞ them¼á eveε removσ ì
ááááátheφá froφ you≥ AUTOEXEC.BA╘ file¼á theε reboo⌠ thσá system«  ì
áááááTry the program again.  If it still crashes ...

áááááMake sure you are calling quiet() before the program exits.

.paè

                           ==========
                           CHANGE LOG
                           ==========

Version 1.0b  (OPEN)

        Added new file SOUNDP.H containing prototypes for all
        user-callable functions, for compilers which support
        prototyping.

        Added support for Ecosoft Eco-C88 compiler.

        Compressed definition of Install in SOUNDCTL, by combining
        all definitions using typedef's and #defines to allow for
        compiler and library differences.


Version 1.0a  (2/20/85)

        Delay now written in assembler.

        Corrected error in play(), which would not play dotted
        notes if a length was also specified.

        Corrected error in SOUND.H's definition of MS2TICKS, which
        was miscalculated and rounding badly.